home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / gnu / makestds.tex < prev    next >
Text File  |  1993-07-18  |  18KB  |  483 lines

  1. @comment This file is included by both standards.texi and make.texinfo.
  2. @comment It was broken out of standards.texi on 1/6/93 by roland.
  3.  
  4. @node Makefile Conventions
  5. @chapter Makefile Conventions
  6. @comment standards.texi does not print an index, but make.texinfo does.
  7. @cindex makefile, conventions for
  8. @cindex conventions for makefiles
  9. @cindex standards for makefiles
  10.  
  11. This chapter describes conventions for writing the Makefiles for GNU programs.
  12.  
  13. @menu
  14. * Makefile Basics::
  15. * Utilities in Makefiles::
  16. * Standard Targets::
  17. * Command Variables::
  18. * Directory Variables::
  19. @end menu
  20.  
  21. @node Makefile Basics
  22. @section General Conventions for Makefiles
  23.  
  24. Every Makefile should contain this line:
  25.  
  26. @example
  27. SHELL = /bin/sh
  28. @end example
  29.  
  30. @noindent
  31. to avoid trouble on systems where the @code{SHELL} variable might be
  32. inherited from the environment.  (This is never a problem with GNU
  33. @code{make}.)
  34.  
  35. Don't assume that @file{.} is in the path for command execution.  When
  36. you need to run programs that are a part of your package during the
  37. make, please make sure that it uses @file{./} if the program is built as
  38. part of the make or @file{$(srcdir)/} if the file is an unchanging part
  39. of the source code.  Without one of these prefixes, the current search
  40. path is used.  
  41.  
  42. The distinction between @file{./} and @file{$(srcdir)/} is important
  43. when using the @samp{--srcdir} option to @file{configure}.  A rule of
  44. the form:
  45.  
  46. @example
  47. foo.1 : foo.man sedscript
  48.         sed -e sedscript foo.man > foo.1
  49. @end example
  50.  
  51. @noindent
  52. will fail when the current directory is not the source directory,
  53. because @file{foo.man} and @file{sedscript} are not in the current
  54. directory.
  55.  
  56. When using GNU @code{make}, relying on @samp{VPATH} to find the source
  57. file will work in the case where there is a single dependency file,
  58. since the @file{make} automatic variable @samp{$<} will represent the
  59. source file wherever it is.  (Many versions of @code{make} set @samp{$<}
  60. only in implicit rules.)  A makefile target like
  61.  
  62. @example
  63. foo.o : bar.c
  64.         $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
  65. @end example
  66.  
  67. @noindent
  68. should instead be written as
  69.  
  70. @example
  71. foo.o : bar.c
  72.         $(CC) $(CFLAGS) $< -o $@@
  73. @end example
  74.  
  75. @noindent
  76. in order to allow @samp{VPATH} to work correctly.  When the target has
  77. multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
  78. way to make the rule work well.  For example, the target above for
  79. @file{foo.1} is best written as:
  80.  
  81. @example
  82. foo.1 : foo.man sedscript
  83.         sed -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1
  84. @end example
  85.  
  86. @node Utilities in Makefiles
  87. @section Utilities in Makefiles
  88.  
  89. Write the Makefile commands (and any shell scripts, such as
  90. @code{configure}) to run in @code{sh}, not in @code{csh}.  Don't use any
  91. special features of @code{ksh} or @code{bash}.
  92.  
  93. The @code{configure} script and the Makefile rules for building and
  94. installation should not use any utilities directly except these:
  95.  
  96. @example
  97. cat cmp cp echo egrep expr grep
  98. ln mkdir mv pwd rm rmdir sed test touch
  99. @end example
  100.  
  101. Stick to the generally supported options for these programs.  For
  102. example, don't use @samp{mkdir -p}, convenient as it may be, because
  103. most systems don't support it.
  104.  
  105. The Makefile rules for building and installation can also use compilers
  106. and related programs, but should do so via @code{make} variables so that the
  107. user can substitute alternatives.  Here are some of the programs we
  108. mean:
  109.  
  110. @example
  111. ar bison cc flex install ld lex
  112. make makeinfo ranlib texi2dvi yacc
  113. @end example
  114.  
  115. When you use @code{ranlib}, you should test whether it exists, and run
  116. it only if it exists, so that the distribution will work on systems that
  117. don't have @code{ranlib}.
  118.  
  119. If you use symbolic links, you should implement a fallback for systems
  120. that don't have symbolic links.
  121.  
  122. It is ok to use other utilities in Makefile portions (or scripts)
  123. intended only for particular systems where you know those utilities to
  124. exist.
  125.  
  126. @node Standard Targets
  127. @section Standard Targets for Users
  128.  
  129. All GNU programs should have the following targets in their Makefiles:
  130.  
  131. @table @samp
  132. @item all
  133. Compile the entire program.  This should be the default target.  This
  134. target need not rebuild any documentation files; info files should
  135. normally be included in the distribution, and DVI files should be made
  136. only when explicitly asked for.
  137.  
  138. @item install
  139. Compile the program and copy the executables, libraries, and so on to
  140. the file names where they should reside for actual use.  If there is a
  141. simple test to verify that a program is properly installed then run that
  142. test.
  143.  
  144. Use @samp{-} before any command for installing a man page, so that
  145. @code{make} will ignore any errors.  This is in case there are systems
  146. that don't have the Unix man page documentation system installed.
  147.  
  148. In the future, when we have a standard way of installing info files,
  149. @samp{install} targets will be the proper place to do so.
  150.  
  151. @item uninstall
  152. Delete all the installed files that the @samp{install} target would
  153. create (but not the noninstalled files such as @samp{make all} would
  154. create).
  155.  
  156. @item clean
  157. Delete all files from the current directory that are normally created by
  158. building the program.  Don't delete the files that record the
  159. configuration.  Also preserve files that could be made by building, but
  160. normally aren't because the distribution comes with them.
  161.  
  162. Delete @file{.dvi} files here if they are not part of the distribution.
  163.  
  164. @item distclean
  165. Delete all files from the current directory that are created by
  166. configuring or building the program.  If you have unpacked the source
  167. and built the program without creating any other files, @samp{make
  168. distclean} should leave only the files that were in the distribution.
  169.  
  170. @item mostlyclean
  171. Like @samp{clean}, but may refrain from deleting a few files that people
  172. normally don't want to recompile.  For example, the @samp{mostlyclean}
  173. target for GCC does not delete @file{libgcc.a}, because recompiling it
  174. is rarely necessary and takes a lot of time.
  175.  
  176. @item realclean
  177. Delete everything from the current directory that can be reconstructed
  178. with this Makefile.  This typically includes everything deleted by
  179. distclean, plus more: C source files produced by Bison, tags tables,
  180. info files, and so on.
  181.  
  182. One exception, however: @samp{make realclean} should not delete
  183. @file{configure} even if @file{configure} can be remade using a rule in
  184. the Makefile.  More generally, @samp{make realclean} should not delete
  185. anything that needs to exist in order to run @file{configure}
  186. and then begin to build the program.
  187.  
  188. @item TAGS
  189. Update a tags table for this program.
  190.  
  191. @item info
  192. Generate any info files needed.  The best way to write the rules is as
  193. follows:
  194.  
  195. @example
  196. info:  foo.info
  197.  
  198. foo.info: $(srcdir)/foo.texi $(srcdir)/chap1.texi $(srcdir)/chap2.texi
  199.         $(MAKEINFO) $(srcdir)/foo.texi
  200. @end example
  201.  
  202. @noindent
  203. You must define the variable @code{MAKEINFO} in the Makefile.
  204. It should run the Makeinfo program, which is part of the Texinfo2 distribution.
  205.  
  206. @item dvi
  207. Generate DVI files for all TeXinfo documentation.  
  208. For example:
  209.  
  210. @example
  211. dvi: foo.dvi
  212.  
  213. foo.dvi: $(srcdir)/foo.texi $(srcdir)/chap1.texi $(srcdir)/chap2.texi
  214.         $(TEXI2DVI) $(srcdir)/foo.texi
  215. @end example
  216.  
  217. @noindent
  218. You must define the variable @code{TEXI2DVI} in the Makefile.  It should
  219. run the program @code{texi2dvi}, which is part of the Texinfo2
  220. distribution.  Alternatively, write just the dependencies, and allow GNU
  221. Make to provide the command.
  222.  
  223. @item dist
  224. Create a distribution tar file for this program.  The tar file should be
  225. set up so that the file names in the tar file start with a subdirectory
  226. name which is the name of the package it is a distribution for.  This
  227. name can include the version number.
  228.  
  229. For example, the distribution tar file of GCC version 1.40 unpacks into
  230. a subdirectory named @file{gcc-1.40}.
  231.  
  232. The easiest way to do this is to create a subdirectory appropriately
  233. named, use @code{ln} or @code{cp} to install the proper files in it, and
  234. then @code{tar} that subdirectory.
  235.  
  236. The @code{dist} target should explicitly depend on all non-source files
  237. that are in the distribution, to make sure they are up to date in the
  238. distribution.  
  239. @xref{Releases, , Making Releases, standards, GNU Coding Standards}.
  240.  
  241. @item check
  242. Perform self-tests (if any).  The user must build the program before
  243. running the tests, but need not install the program; you should write
  244. the self-tests so that they work when the program is built but not
  245. installed.
  246. @end table
  247.  
  248. The following targets are suggested as conventional names, for programs
  249. in which they are useful.
  250.  
  251. @table @code
  252. @item installcheck
  253. Perform installation tests (if any).  The user must build and install
  254. the program before running the tests.  You should not assume that
  255. @file{$(bindir)} is in the search path.  
  256.  
  257. @item installdirs
  258. It's useful to add a target named @samp{installdirs} to create the
  259. directories where files are installed, and their parent directories.
  260. There is a script called @file{mkinstalldirs} which is convenient for
  261. this; find it in the Texinfo package.@c It's in /gd/gnu/lib/mkinstalldirs.
  262. You can use a rule like this:
  263.  
  264. @example
  265. # Make sure all installation directories, e.g. $(bindir) actually exist by
  266. # making them if necessary.
  267. installdirs: mkinstalldirs
  268.         $(srcdir)/mkinstalldirs $(bindir) $(datadir) $(libdir) \
  269.                                 $(infodir) $(mandir)
  270. @end example
  271. @end table
  272.  
  273. @node Command Variables
  274. @section Variables for Specifying Commands
  275.  
  276. Makefiles should provide variables for overriding certain commands, options,
  277. and so on.
  278.  
  279. In particular, you should run most utility programs via variables.
  280. Thus, if you use Bison, have a variable named @code{BISON} whose default
  281. value is set with @samp{BISON = bison}, and refer to it with
  282. @code{$(BISON)} whenever you need to use Bison.
  283.  
  284. File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
  285. so on, need not be referred to through variables in this way, since users
  286. don't need to replace them with other programs.
  287.  
  288. Each program-name variable should come with an options variable that is
  289. used to supply options to the program.  Append @samp{FLAGS} to the
  290. program-name variable name to get the options variable name---for
  291. example, @code{BISONFLAGS}.  (The name @code{CFLAGS} is an exception to
  292. this rule, but we keep it because it is standard.)  Use @code{CPPFLAGS}
  293. in any compilation command that runs the preprocessor, and use
  294. @code{LDFLAGS} in any compilation command that does linking as well as
  295. in any direct use of @code{ld}.
  296.  
  297. If there are C compiler options that @emph{must} be used for proper
  298. compilation of certain files, do not include them in @code{CFLAGS}.
  299. Users expect to be able to specify @code{CFLAGS} freely themselves.
  300. Instead, arrange to pass the necessary options to the C compiler
  301. independently of @code{CFLAGS}, by writing them explicitly in the
  302. compilation commands or by defining an implicit rule, like this:
  303.  
  304. @example
  305. CFLAGS = -g
  306. ALL_CFLAGS = -I. $(CFLAGS)
  307. .c.o:
  308.         $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
  309. @end example
  310.  
  311. Do include the @samp{-g} option in @code{CFLAGS}, because that is not
  312. @emph{required} for proper compilation.  You can consider it a default
  313. that is only recommended.  If the package is set up so that it is
  314. compiled with GCC by default, then you might as well include @samp{-O}
  315. in the default value of @code{CFLAGS} as well.
  316.  
  317. Put @code{CFLAGS} last in the compilation command, after other variables
  318. containing compiler options, so the user can use @code{CFLAGS} to
  319. override the others.
  320.  
  321. Every Makefile should define the variable @code{INSTALL}, which is the
  322. basic command for installing a file into the system.
  323.  
  324. Every Makefile should also define variables @code{INSTALL_PROGRAM} and
  325. @code{INSTALL_DATA}.  (The default for each of these should be
  326. @code{$(INSTALL)}.)  Then it should use those variables as the commands
  327. for actual installation, for executables and nonexecutables
  328. respectively.  Use these variables as follows:
  329.  
  330. @example
  331. $(INSTALL_PROGRAM) foo $(bindir)/foo
  332. $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
  333. @end example
  334.  
  335. @noindent
  336. Always use a file name, not a directory name, as the second argument of
  337. the installation commands.  Use a separate command for each file to be
  338. installed.
  339.  
  340. @node Directory Variables
  341. @section Variables for Installation Directories
  342.  
  343. Installation directories should always be named by variables, so it is
  344. easy to install in a nonstandard place.  The standard names for these
  345. variables are:
  346.  
  347. @table @samp
  348. @item prefix
  349. A prefix used in constructing the default values of the variables listed
  350. below.  The default value of @code{prefix} should be @file{/usr/local}
  351. (at least for now).
  352.  
  353. @item exec_prefix
  354. A prefix used in constructing the default values of the some of the
  355. variables listed below.  The default value of @code{exec_prefix} should
  356. be @code{$(prefix)}.
  357.  
  358. Generally, @code{$(exec_prefix)} is used for directories that contain
  359. machine-specific files (such as executables and subroutine libraries),
  360. while @code{$(prefix)} is used directly for other directories.
  361.  
  362. @item bindir
  363. The directory for installing executable programs that users can run.
  364. This should normally be @file{/usr/local/bin}, but write it as
  365. @file{$(exec_prefix)/bin}.
  366.  
  367. @item libdir
  368. The directory for installing executable files to be run by the program
  369. rather than by users.  Object files and libraries of object code should
  370. also go in this directory.  The idea is that this directory is used for
  371. files that pertain to a specific machine architecture, but need not be
  372. in the path for commands.  The value of @code{libdir} should normally be
  373. @file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
  374.  
  375. @item datadir
  376. The directory for installing read-only data files which the programs
  377. refer to while they run.  This directory is used for files which are
  378. independent of the type of machine being used.  This should normally be
  379. @file{/usr/local/lib}, but write it as @file{$(prefix)/lib}.
  380.  
  381. @item statedir
  382. The directory for installing data files which the programs modify while
  383. they run.  These files should be independent of the type of machine
  384. being used, and it should be possible to share them among machines at a
  385. network installation.  This should normally be @file{/usr/local/lib},
  386. but write it as @file{$(prefix)/lib}.
  387.  
  388. @item includedir
  389. @c rewritten to avoid overfull hbox --roland
  390. The directory for installing header files to be included by user
  391. programs with the C @samp{#include} preprocessor directive.  This
  392. should normally be @file{/usr/local/include}, but write it as
  393. @file{$(prefix)/include}.
  394.  
  395. Most compilers other than GCC do not look for header files in
  396. @file{/usr/local/include}.  So installing the header files this way is
  397. only useful with GCC.  Sometimes this is not a problem because some
  398. libraries are only really intended to work with GCC.  But some libraries
  399. are intended to work with other compilers.  They should install their
  400. header files in two places, one specified by @code{includedir} and one
  401. specified by @code{oldincludedir}.
  402.  
  403. @item oldincludedir
  404. The directory for installing @samp{#include} header files for use with
  405. compilers other than GCC.  This should normally be @file{/usr/include}.
  406.  
  407. The Makefile commands should check whether the value of
  408. @code{oldincludedir} is empty.  If it is, they should not try to use
  409. it; they should cancel the second installation of the header files.
  410.  
  411. A package should not replace an existing header in this directory unless
  412. the header came from the same package.  Thus, if your Foo package
  413. provides a header file @file{foo.h}, then it should install the header
  414. file in the @code{oldincludedir} directory if either (1) there is no
  415. @file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
  416. package.
  417.  
  418. The way to tell whether @file{foo.h} came from the Foo package is to put
  419. a magic string in the file---part of a comment---and grep for that
  420. string.
  421.  
  422. @item mandir
  423. The directory for installing the man pages (if any) for this package.
  424. It should include the suffix for the proper section of the
  425. manual---usually @samp{1} for a utility.
  426.  
  427. @item man1dir
  428. The directory for installing section 1 man pages.
  429. @item man2dir
  430. The directory for installing section 2 man pages.
  431. @item @dots{}
  432. Use these names instead of @samp{mandir} if the package needs to install man
  433. pages in more than one section of the manual.
  434.  
  435. @strong{Don't make the primary documentation for any GNU software be a
  436. man page.  Write a manual in Texinfo instead.  Man pages are just for
  437. the sake of people running GNU software on Unix, which is a secondary
  438. application only.}
  439.  
  440. @item manext
  441. The file name extension for the installed man page.  This should contain
  442. a period followed by the appropriate digit.
  443.  
  444. @item infodir
  445. The directory for installing the info files for this package.  By
  446. default, it should be @file{/usr/local/info}, but it should be written
  447. as @file{$(prefix)/info}.
  448.  
  449. @item srcdir
  450. The directory for the sources being compiled.  The value of this
  451. variable is normally inserted by the @code{configure} shell script.
  452. @end table
  453.  
  454. For example:
  455.  
  456. @example
  457. @c I have changed some of the comments here slightly to fix an overfull
  458. @c hbox, so the make manual can format correctly. --roland
  459. # Common prefix for installation directories.
  460. # NOTE: This directory must exist when you start the install.
  461. prefix = /usr/local
  462. exec_prefix = $(prefix)
  463. # Where to put the executable for the command `gcc'.
  464. bindir = $(exec_prefix)/bin
  465. # Where to put the directories used by the compiler.
  466. libdir = $(exec_prefix)/lib
  467. # Where to put the Info files.
  468. infodir = $(prefix)/info
  469. @end example
  470.  
  471. If your program installs a large number of files into one of the
  472. standard user-specified directories, it might be useful to group them
  473. into a subdirectory particular to that program.  If you do this, you
  474. should write the @code{install} rule to create these subdirectories.
  475.  
  476. Do not expect the user to include the subdirectory name in the value of
  477. any of the variables listed above.  The idea of having a uniform set of
  478. variable names for installation directories is to enable the user to
  479. specify the exact same values for several different GNU packages.  In
  480. order for this to be useful, all the packages must be designed so that
  481. they will work sensibly when the user does so.
  482.  
  483.